
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
    <title>Key locations &#8212; PSA Crypto API 1.0.0 documentation</title>
    <link rel="stylesheet" href="../../_static/alabaster.css" type="text/css" />
    <link rel="stylesheet" href="../../_static/pygments.css" type="text/css" />
    <script type="text/javascript">
      var DOCUMENTATION_OPTIONS = {
        URL_ROOT:    '../../',
        VERSION:     '1.0.0',
        COLLAPSE_INDEX: false,
        FILE_SUFFIX: '.html',
        HAS_SOURCE:  true,
        SOURCELINK_SUFFIX: '.txt'
      };
    </script>
    <script type="text/javascript" src="../../_static/jquery.js"></script>
    <script type="text/javascript" src="../../_static/underscore.js"></script>
    <script type="text/javascript" src="../../_static/doctools.js"></script>
    <link rel="index" title="Index" href="../../genindex.html" />
    <link rel="search" title="Search" href="../../search.html" />
    <link rel="next" title="Key types" href="types.html" />
    <link rel="prev" title="Key attributes" href="attributes.html" />
   
  <link rel="stylesheet" href="../../_static/custom.css" type="text/css" />
  
  <meta name="viewport" content="width=device-width, initial-scale=0.9, maximum-scale=0.9" />

  </head>
  <body>
  

    <div class="document">
      <div class="documentwrapper">
        <div class="bodywrapper">
          <div class="body" role="main">
            
  <div class="section" id="key-locations">
<span id="id1"></span><h1>Key locations</h1>
<div class="section" id="key-lifetimes">
<h2>Key lifetimes</h2>
<div class="section" id="PSA_KEY_LIFETIME_VOLATILE">
<span id="c.PSA_KEY_LIFETIME_VOLATILE"></span><h3><code class="docutils literal"><span class="pre">PSA_KEY_LIFETIME_VOLATILE</span></code> (macro)</h3>
<p>A lifetime value that indicates a volatile key.</p>
<pre class="literal-block">
#define <a class="reference internal" href="#c.PSA_KEY_LIFETIME_VOLATILE" title="PSA_KEY_LIFETIME_VOLATILE">PSA_KEY_LIFETIME_VOLATILE</a> ((<a class="reference internal" href="attributes.html#c.psa_key_lifetime_t" title="psa_key_lifetime_t">psa_key_lifetime_t</a>)0x00000000)
</pre>
<p>A volatile key only exists as long as the identifier to it is not destroyed.</p>
<p>The key material is guaranteed to be erased on a power reset.</p>
</div>
<div class="section" id="PSA_KEY_LIFETIME_PERSISTENT">
<span id="c.PSA_KEY_LIFETIME_PERSISTENT"></span><h3><code class="docutils literal"><span class="pre">PSA_KEY_LIFETIME_PERSISTENT</span></code> (macro)</h3>
<p>The default storage area for persistent keys.</p>
<pre class="literal-block">
#define <a class="reference internal" href="#c.PSA_KEY_LIFETIME_PERSISTENT" title="PSA_KEY_LIFETIME_PERSISTENT">PSA_KEY_LIFETIME_PERSISTENT</a> ((<a class="reference internal" href="attributes.html#c.psa_key_lifetime_t" title="psa_key_lifetime_t">psa_key_lifetime_t</a>)0x00000001)
</pre>
<p>A persistent key remains in storage until it is explicitly destroyed or until the corresponding storage area is wiped. This specification does not define any mechanism to wipe a storage area. Implementations are permitted to provide their own mechanism, for example, to perform a factory reset, to prepare for device refurbishment, or to uninstall an application.</p>
<p>This lifetime value is the default storage area for the calling application. Implementations can offer other storage areas designated by other lifetime values as implementation-specific extensions.</p>
</div>
</div>
<div class="section" id="key-identifiers">
<span id="id2"></span><h2>Key identifiers</h2>
<div class="section" id="PSA_KEY_ID_NULL">
<span id="c.PSA_KEY_ID_NULL"></span><h3><code class="docutils literal"><span class="pre">PSA_KEY_ID_NULL</span></code> (macro)</h3>
<p>The null key identifier.</p>
<pre class="literal-block">
#define <a class="reference internal" href="#c.PSA_KEY_ID_NULL" title="PSA_KEY_ID_NULL">PSA_KEY_ID_NULL</a> ((<a class="reference internal" href="attributes.html#c.psa_key_id_t" title="psa_key_id_t">psa_key_id_t</a>)0)
</pre>
<p>The null key identifier is always invalid, except when used without in a call to <a class="reference internal" href="management.html#c.psa_destroy_key" title="psa_destroy_key"><code class="xref any c c-func docutils literal"><span class="pre">psa_destroy_key()</span></code></a> which will return <a class="reference internal" href="../library/status.html#c.PSA_SUCCESS" title="PSA_SUCCESS"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_SUCCESS</span></code></a>.</p>
</div>
<div class="section" id="PSA_KEY_ID_USER_MIN">
<span id="c.PSA_KEY_ID_USER_MIN"></span><h3><code class="docutils literal"><span class="pre">PSA_KEY_ID_USER_MIN</span></code> (macro)</h3>
<p>The minimum value for a key identifier chosen by the application.</p>
<pre class="literal-block">
#define <a class="reference internal" href="#c.PSA_KEY_ID_USER_MIN" title="PSA_KEY_ID_USER_MIN">PSA_KEY_ID_USER_MIN</a> ((<a class="reference internal" href="attributes.html#c.psa_key_id_t" title="psa_key_id_t">psa_key_id_t</a>)0x00000001)
</pre>
</div>
<div class="section" id="PSA_KEY_ID_USER_MAX">
<span id="c.PSA_KEY_ID_USER_MAX"></span><h3><code class="docutils literal"><span class="pre">PSA_KEY_ID_USER_MAX</span></code> (macro)</h3>
<p>The maximum value for a key identifier chosen by the application.</p>
<pre class="literal-block">
#define <a class="reference internal" href="#c.PSA_KEY_ID_USER_MAX" title="PSA_KEY_ID_USER_MAX">PSA_KEY_ID_USER_MAX</a> ((<a class="reference internal" href="attributes.html#c.psa_key_id_t" title="psa_key_id_t">psa_key_id_t</a>)0x3fffffff)
</pre>
</div>
<div class="section" id="PSA_KEY_ID_VENDOR_MIN">
<span id="c.PSA_KEY_ID_VENDOR_MIN"></span><h3><code class="docutils literal"><span class="pre">PSA_KEY_ID_VENDOR_MIN</span></code> (macro)</h3>
<p>The minimum value for a key identifier chosen by the implementation.</p>
<pre class="literal-block">
#define <a class="reference internal" href="#c.PSA_KEY_ID_VENDOR_MIN" title="PSA_KEY_ID_VENDOR_MIN">PSA_KEY_ID_VENDOR_MIN</a> ((<a class="reference internal" href="attributes.html#c.psa_key_id_t" title="psa_key_id_t">psa_key_id_t</a>)0x40000000)
</pre>
</div>
<div class="section" id="PSA_KEY_ID_VENDOR_MAX">
<span id="c.PSA_KEY_ID_VENDOR_MAX"></span><h3><code class="docutils literal"><span class="pre">PSA_KEY_ID_VENDOR_MAX</span></code> (macro)</h3>
<p>The maximum value for a key identifier chosen by the implementation.</p>
<pre class="literal-block">
#define <a class="reference internal" href="#c.PSA_KEY_ID_VENDOR_MAX" title="PSA_KEY_ID_VENDOR_MAX">PSA_KEY_ID_VENDOR_MAX</a> ((<a class="reference internal" href="attributes.html#c.psa_key_id_t" title="psa_key_id_t">psa_key_id_t</a>)0x7fffffff)
</pre>
</div>
</div>
<div class="section" id="attribute-accessors">
<h2>Attribute accessors</h2>
<div class="section" id="psa_set_key_lifetime">
<span id="c.psa_set_key_lifetime"></span><h3><code class="docutils literal"><span class="pre">psa_set_key_lifetime</span></code> (function)</h3>
<p>Set the location of a persistent key.</p>
<pre class="literal-block">
void <a class="reference internal" href="#c.psa_set_key_lifetime" title="psa_set_key_lifetime">psa_set_key_lifetime</a>(<a class="reference internal" href="attributes.html#c.psa_key_attributes_t" title="psa_key_attributes_t">psa_key_attributes_t</a> * attributes,
                          <a class="reference internal" href="attributes.html#c.psa_key_lifetime_t" title="psa_key_lifetime_t">psa_key_lifetime_t</a> lifetime);
</pre>
<p class="rubric">Parameters</p>
<dl class="docutils">
<dt> <code class="docutils literal"><span class="pre">attributes</span></code></dt>
<dd>The attribute object to write to.</dd>
<dt> <code class="docutils literal"><span class="pre">lifetime</span></code></dt>
<dd>The lifetime for the key. If this is <a class="reference internal" href="#c.PSA_KEY_LIFETIME_VOLATILE" title="PSA_KEY_LIFETIME_VOLATILE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_LIFETIME_VOLATILE</span></code></a>, the key will be volatile, and the key identifier attribute is reset to <a class="reference internal" href="#c.PSA_KEY_ID_NULL" title="PSA_KEY_ID_NULL"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_ID_NULL</span></code></a>.</dd>
</dl>
<p class="rubric">Returns: <code class="docutils literal"><span class="pre">void</span></code></p>
<p class="rubric">Description</p>
<p>To make a key persistent, give it a persistent key identifier by using <a class="reference internal" href="#c.psa_set_key_id" title="psa_set_key_id"><code class="xref any c c-func docutils literal"><span class="pre">psa_set_key_id()</span></code></a>. By default, a key that has a persistent identifier is stored in the default storage area identifier by <a class="reference internal" href="#c.PSA_KEY_LIFETIME_PERSISTENT" title="PSA_KEY_LIFETIME_PERSISTENT"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_LIFETIME_PERSISTENT</span></code></a>. Call this function to choose a storage area, or to explicitly declare the key as volatile.</p>
<p>This function does not access storage, it merely stores the given value in the attribute object. The persistent key will be written to storage when the attribute object is passed to a key creation function such as <a class="reference internal" href="management.html#c.psa_import_key" title="psa_import_key"><code class="xref any c c-func docutils literal"><span class="pre">psa_import_key()</span></code></a>, <a class="reference internal" href="management.html#c.psa_generate_key" title="psa_generate_key"><code class="xref any c c-func docutils literal"><span class="pre">psa_generate_key()</span></code></a>, <a class="reference internal" href="../ops/kdf.html#c.psa_key_derivation_output_key" title="psa_key_derivation_output_key"><code class="xref any c c-func docutils literal"><span class="pre">psa_key_derivation_output_key()</span></code></a> or <a class="reference internal" href="management.html#c.psa_copy_key" title="psa_copy_key"><code class="xref any c c-func docutils literal"><span class="pre">psa_copy_key()</span></code></a>.</p>
<div class="admonition-implementation-note admonition">
<p class="first admonition-title">Implementation note</p>
<p>This is a simple accessor function that is not required to validate its inputs. The following approaches can be used to provide an efficient implementation:</p>
<ul class="last simple">
<li>This function can be declared as <code class="docutils literal"><span class="pre">static</span></code> or <code class="docutils literal"><span class="pre">inline</span></code>, instead of using the default external linkage.</li>
<li>This function can be provided as a function-like macro. In this form, the macro must evaluate each of its arguments exactly once, as if it was a function call.</li>
</ul>
</div>
</div>
<div class="section" id="psa_get_key_lifetime">
<span id="c.psa_get_key_lifetime"></span><h3><code class="docutils literal"><span class="pre">psa_get_key_lifetime</span></code> (function)</h3>
<p>Retrieve the lifetime from key attributes.</p>
<pre class="literal-block">
<a class="reference internal" href="attributes.html#c.psa_key_lifetime_t" title="psa_key_lifetime_t">psa_key_lifetime_t</a> <a class="reference internal" href="#c.psa_get_key_lifetime" title="psa_get_key_lifetime">psa_get_key_lifetime</a>(const <a class="reference internal" href="attributes.html#c.psa_key_attributes_t" title="psa_key_attributes_t">psa_key_attributes_t</a> * attributes);
</pre>
<p class="rubric">Parameters</p>
<dl class="docutils">
<dt> <code class="docutils literal"><span class="pre">attributes</span></code></dt>
<dd>The key attribute object to query.</dd>
</dl>
<p class="rubric">Returns: <a class="reference internal" href="attributes.html#c.psa_key_lifetime_t" title="psa_key_lifetime_t"><code class="docutils literal"><span class="pre">psa_key_lifetime_t</span></code></a></p>
<p>The lifetime value stored in the attribute object.</p>
<p class="rubric">Description</p>
<div class="admonition-implementation-note admonition">
<p class="first admonition-title">Implementation note</p>
<p>This is a simple accessor function that is not required to validate its inputs. The following approaches can be used to provide an efficient implementation:</p>
<ul class="last simple">
<li>This function can be declared as <code class="docutils literal"><span class="pre">static</span></code> or <code class="docutils literal"><span class="pre">inline</span></code>, instead of using the default external linkage.</li>
<li>This function can be provided as a function-like macro. In this form, the macro must evaluate each of its arguments exactly once, as if it was a function call.</li>
</ul>
</div>
</div>
<div class="section" id="psa_set_key_id">
<span id="c.psa_set_key_id"></span><h3><code class="docutils literal"><span class="pre">psa_set_key_id</span></code> (function)</h3>
<p>Declare a key as persistent and set its key identifier.</p>
<pre class="literal-block">
void <a class="reference internal" href="#c.psa_set_key_id" title="psa_set_key_id">psa_set_key_id</a>(<a class="reference internal" href="attributes.html#c.psa_key_attributes_t" title="psa_key_attributes_t">psa_key_attributes_t</a> * attributes,
                    <a class="reference internal" href="attributes.html#c.psa_key_id_t" title="psa_key_id_t">psa_key_id_t</a> id);
</pre>
<p class="rubric">Parameters</p>
<dl class="docutils">
<dt> <code class="docutils literal"><span class="pre">attributes</span></code></dt>
<dd>The attribute object to write to.</dd>
<dt> <code class="docutils literal"><span class="pre">id</span></code></dt>
<dd>The persistent identifier for the key.</dd>
</dl>
<p class="rubric">Returns: <code class="docutils literal"><span class="pre">void</span></code></p>
<p class="rubric">Description</p>
<p>If the attribute object currently declares the key as volatile, which is the default lifetime of an attribute object, this function sets the lifetime attribute to <a class="reference internal" href="#c.PSA_KEY_LIFETIME_PERSISTENT" title="PSA_KEY_LIFETIME_PERSISTENT"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_LIFETIME_PERSISTENT</span></code></a>.</p>
<p>This function does not access storage, it merely stores the given value in the attribute object. The persistent key will be written to storage when the attribute object is passed to a key creation function such as <a class="reference internal" href="management.html#c.psa_import_key" title="psa_import_key"><code class="xref any c c-func docutils literal"><span class="pre">psa_import_key()</span></code></a>, <a class="reference internal" href="management.html#c.psa_generate_key" title="psa_generate_key"><code class="xref any c c-func docutils literal"><span class="pre">psa_generate_key()</span></code></a>, <a class="reference internal" href="../ops/kdf.html#c.psa_key_derivation_output_key" title="psa_key_derivation_output_key"><code class="xref any c c-func docutils literal"><span class="pre">psa_key_derivation_output_key()</span></code></a> or <a class="reference internal" href="management.html#c.psa_copy_key" title="psa_copy_key"><code class="xref any c c-func docutils literal"><span class="pre">psa_copy_key()</span></code></a>.</p>
<div class="admonition-implementation-note admonition">
<p class="first admonition-title">Implementation note</p>
<p>This is a simple accessor function that is not required to validate its inputs. The following approaches can be used to provide an efficient implementation:</p>
<ul class="last simple">
<li>This function can be declared as <code class="docutils literal"><span class="pre">static</span></code> or <code class="docutils literal"><span class="pre">inline</span></code>, instead of using the default external linkage.</li>
<li>This function can be provided as a function-like macro. In this form, the macro must evaluate each of its arguments exactly once, as if it was a function call.</li>
</ul>
</div>
</div>
<div class="section" id="psa_get_key_id">
<span id="c.psa_get_key_id"></span><h3><code class="docutils literal"><span class="pre">psa_get_key_id</span></code> (function)</h3>
<p>Retrieve the key identifier from key attributes.</p>
<pre class="literal-block">
<a class="reference internal" href="attributes.html#c.psa_key_id_t" title="psa_key_id_t">psa_key_id_t</a> <a class="reference internal" href="#c.psa_get_key_id" title="psa_get_key_id">psa_get_key_id</a>(const <a class="reference internal" href="attributes.html#c.psa_key_attributes_t" title="psa_key_attributes_t">psa_key_attributes_t</a> * attributes);
</pre>
<p class="rubric">Parameters</p>
<dl class="docutils">
<dt> <code class="docutils literal"><span class="pre">attributes</span></code></dt>
<dd>The key attribute object to query.</dd>
</dl>
<p class="rubric">Returns: <a class="reference internal" href="attributes.html#c.psa_key_id_t" title="psa_key_id_t"><code class="docutils literal"><span class="pre">psa_key_id_t</span></code></a></p>
<p>The persistent identifier stored in the attribute object. This value is unspecified if the attribute object declares the key as volatile.</p>
<p class="rubric">Description</p>
<div class="admonition-implementation-note admonition">
<p class="first admonition-title">Implementation note</p>
<p>This is a simple accessor function that is not required to validate its inputs. The following approaches can be used to provide an efficient implementation:</p>
<ul class="last simple">
<li>This function can be declared as <code class="docutils literal"><span class="pre">static</span></code> or <code class="docutils literal"><span class="pre">inline</span></code>, instead of using the default external linkage.</li>
<li>This function can be provided as a function-like macro. In this form, the macro must evaluate each of its arguments exactly once, as if it was a function call.</li>
</ul>
</div>
</div>
</div>
</div>


          </div>
        </div>
      </div>
      <div class="sphinxsidebar" role="navigation" aria-label="main navigation">
        <div class="sphinxsidebarwrapper">
  <h3><a href="../../index.html">Table Of Contents</a></h3>
  <ul>
<li><a class="reference internal" href="#">Key locations</a><ul>
<li><a class="reference internal" href="#key-lifetimes">Key lifetimes</a><ul>
<li><a class="reference internal" href="#PSA_KEY_LIFETIME_VOLATILE"><code class="docutils literal"><span class="pre">PSA_KEY_LIFETIME_VOLATILE</span></code> (macro)</a></li>
<li><a class="reference internal" href="#PSA_KEY_LIFETIME_PERSISTENT"><code class="docutils literal"><span class="pre">PSA_KEY_LIFETIME_PERSISTENT</span></code> (macro)</a></li>
</ul>
</li>
<li><a class="reference internal" href="#key-identifiers">Key identifiers</a><ul>
<li><a class="reference internal" href="#PSA_KEY_ID_NULL"><code class="docutils literal"><span class="pre">PSA_KEY_ID_NULL</span></code> (macro)</a></li>
<li><a class="reference internal" href="#PSA_KEY_ID_USER_MIN"><code class="docutils literal"><span class="pre">PSA_KEY_ID_USER_MIN</span></code> (macro)</a></li>
<li><a class="reference internal" href="#PSA_KEY_ID_USER_MAX"><code class="docutils literal"><span class="pre">PSA_KEY_ID_USER_MAX</span></code> (macro)</a></li>
<li><a class="reference internal" href="#PSA_KEY_ID_VENDOR_MIN"><code class="docutils literal"><span class="pre">PSA_KEY_ID_VENDOR_MIN</span></code> (macro)</a></li>
<li><a class="reference internal" href="#PSA_KEY_ID_VENDOR_MAX"><code class="docutils literal"><span class="pre">PSA_KEY_ID_VENDOR_MAX</span></code> (macro)</a></li>
</ul>
</li>
<li><a class="reference internal" href="#attribute-accessors">Attribute accessors</a><ul>
<li><a class="reference internal" href="#psa_set_key_lifetime"><code class="docutils literal"><span class="pre">psa_set_key_lifetime</span></code> (function)</a></li>
<li><a class="reference internal" href="#psa_get_key_lifetime"><code class="docutils literal"><span class="pre">psa_get_key_lifetime</span></code> (function)</a></li>
<li><a class="reference internal" href="#psa_set_key_id"><code class="docutils literal"><span class="pre">psa_set_key_id</span></code> (function)</a></li>
<li><a class="reference internal" href="#psa_get_key_id"><code class="docutils literal"><span class="pre">psa_get_key_id</span></code> (function)</a></li>
</ul>
</li>
</ul>
</li>
</ul>
<div class="relations">
<h3>Related Topics</h3>
<ul>
  <li><a href="../../index.html">Documentation overview</a><ul>
  <li><a href="index.html">Key management reference</a><ul>
      <li>Previous: <a href="attributes.html" title="previous chapter">Key attributes</a></li>
      <li>Next: <a href="types.html" title="next chapter">Key types</a></li>
  </ul></li>
  </ul></li>
</ul>
</div>
  <div role="note" aria-label="source link">
    <h3>This Page</h3>
    <ul class="this-page-menu">
      <li><a href="../../_sources/api/keys/locations.rst.txt"
            rel="nofollow">Show Source</a></li>
    </ul>
   </div>
<div id="searchbox" style="display: none" role="search">
  <h3>Quick search</h3>
    <form class="search" action="../../search.html" method="get">
      <div><input type="text" name="q" /></div>
      <div><input type="submit" value="Go" /></div>
      <input type="hidden" name="check_keywords" value="yes" />
      <input type="hidden" name="area" value="default" />
    </form>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
        </div>
      </div>
      <div class="clearer"></div>
    </div>
    <div class="footer">
      &copy; 2019-2020, Arm Limited or its affiliates. All rights reserved.
      
      |
      Powered by <a href="http://sphinx-doc.org/">Sphinx 1.6.7</a>
      &amp; <a href="https://github.com/bitprophet/alabaster">Alabaster 0.7.8</a>
      
      |
      <a href="../../_sources/api/keys/locations.rst.txt"
          rel="nofollow">Page source</a>
    </div>

    

    
  </body>
</html>